/*
    PonySE word segmenter
    Copyright (C) 2007-2008 PonySE

    This program is free software: you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation, either version 3 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program.  If not, see <http://www.gnu.org/licenses/>.
*/

/**
 * PonySE word segmenter header file 
 * @file pws.h
 * @brief PonySE word segment header file
 * @version 0.0.2
 * @author chengyan
 * @date 03/07/2008 0.0.2 change name to "PonySE word segment"
 * @date 03/07/2008 0.0.1 add function ws_get_words(), by chengyan
 * @date 12/27/2007 0.0.0 created, by chengyan
 */

#ifndef __PONYSE_WORDSEGMENTER_H__
#define __PONYSE_WORDSEGMENTER_H__

#ifdef __cplusplus
extern "C" {
#endif /* __cplusplus */

/**
 * word segmentation result
 * It's a abstract type, you can operation it by functions pws_res_*()
 */
typedef struct pws_result pws_result_t;

/**
 * initialize PonySE word segmenter
 * @param dict_path [in] the dictionary of word segmenter 
 * @return Return 0 if succeed, otherwise return other values:
 * 	-1 - parameter invalidate
 * 	-2 - open dictionary file failed.
 * 	-3 - memory error
 */
int pws_initialize( const char * dict_path );

/**
 * segment content to wordid array(saved in pws_result_obj)
 * @param content          [in]     the content to be segment
 * @param len              [in]     content length
 * @param pws_result_obj   [in,out] a ws_result_t object
 */
void pws_segment( const char * content, long len, pws_result_t * pws_result_obj );

/**
 * segment content to wordid array and words string array(saved in pws_result_obj)
 * @param content          [in]     the content to be segment
 * @param len              [in]     content length
 * @param pws_result_obj   [in,out] a ws_result_t object
 */
void pws_segment_full( const char * content, long len, pws_result_t * pws_result_obj );

/**
 * release PonySE word segment
 */
void pws_release();

/**
 * create a pws_result_t object
 * @return Return the new created pws_result_t object if succeed, else return 0
 */
pws_result_t * pws_res_create();

/**
 * only clean a pws_result_t object
 * @param pws_result_obj The pws_result_t object to be clean
 */
void pws_res_clean( pws_result_t * pws_result_obj );

/**
 * free and destroy a pws_result_t object which created by function pws_res_create
 * @param pws_result_obj [in, out] pws_result_t object to be freed
 */
void pws_res_free( pws_result_t ** pws_result_obj );

/**
 * get words' identification number with a pws_result_obj
 * @param pws_result_obj   [in]     a pws_result_t object
 * @param wordid           [in, out] words' identification
 * @return Return the size of words' identification list
 * @example
 * 	long * wordid = 0;
 * 	...
 * 	pws_setment( content, pws_result_obj );
 * 	long i = pws_res_wordid( pws_result_obj, &wordid );
 * 	...
 *
 * 	you will be get:
 * 	i = 3
 * 	wordid = { 103012, 230, 88203 }
 */
long pws_res_wordid( const pws_result_t * pws_result_obj, long ** wordid );

/**
 * get words' identification number and word details with a pws_result_obj
 * @param pws_result_obj   [in]      a pws_result_t object
 * @param wordid           [in, out] words' identification
 * @param word             [in, out] words' details
 * @return Return the size of words' identification list
 * @example
 * 	long * wordid = 0;
 * 	const char ** words = 0;
 * 	...
 * 	pws_segment_full( content, pws_result_obj );
 * 	long i = pws_res_word( pws_result_obj, &wordid, &words );
 * 	...
 *
 * 	you will be get:
 * 	i = 3
 * 	wordid = { 103012, 230, 88203 }
 * 	words  = { "google", "yahoo", "baidu" }
 */
long pws_res_words( const pws_result_t * pws_result_obj, long ** wordid, const char *** word );

#ifdef __cplusplus
}
#endif /* __cplusplus */

#endif /* __PONYSE_WORDSEGMENTER_H__ */


